Subroutine API Overview
Release 5.1.0 of the APPX Utility includes a new standardized designer API which can be used to gain access to extended functionality from within an APPX application. This API provides APPX Designers with a robust set of subroutines which can be called to do a variety of tasks. This API replaces the older subroutines that have been informally used, and all designers are encouraged to begin using the new subroutines.
General Information
All of these new subroutines are defined in the (---) application and begin with a period (.). They all use a standard call interface and use the same framework for returning results and reporting errors. They are grouped by name prefix so that related subroutines are grouped together by function. Data is passed into and returned from these subroutines by use of the PASS statement. Failure information is returned by use of a work field with the same name as the subroutine. This failure code field is tokenized so you can scan to see the failure reasons that can be returned. Note that the work field has a scope of 'Detached', and so will retain it's value from invocation to invocation, as well as across all invocation types.
If the subroutine accepts parameters (i.e., READ, WRITE, APPEND to --- .STREAM OPEN), the parameters are case insensitive.
If the subroutine has required parameters and you do not PASS the correct number of parameters, the subroutine will issue a CANCEL identifying which parameter was missing.
General Routines
Application Routines Contains routines to change the current application phase (Live Operations, Recovery Processing, Initial Setup) or to select a new database.
|
API Name |
Description |
|
.BEGIN INITIAL SETUP |
Changes the current application to the 'Initial Setup' phase. |
|
.BEGIN LIVE OPERATIONS |
Changes the current application to the 'Live Operations' phase. |
|
.BEGIN RECOVERY PROCESSING |
Changes the current application to the 'Recovery Processing' phase. |
|
.SELECT DATABASE |
Switches to the specified database. |
Utility Routines Contains routines to add/change/delete a user, change a user's auxiliary password, test a user's security code, add/change/delete Hook records, activate temporary Hook records, compile processes, process the Data Dictionary, switch user context, update application documentation, pause execution for a specified number of seconds (with or without a countdown timer), implement timeouts, indirect field referencing (to set or retrieve a field value by name), and more.
|
API Name |
Description |
|
.UTIL ADD USER |
Adds a user to the Appx User file. |
|
.UTIL ADD HOOK |
Adds a record to the Hook file. |
|
.UTIL CHECK SECURITY |
Checks the security code for the specified user. |
|
.UTIL CHG AUX PASS |
Changes the Auxiliary password for the specified user. |
|
.UTIL CHG HOOK |
Changes fields on the Hook File. |
|
.UTIL CHG USER |
Changes fields on the Appx User File. |
|
.UTIL CLEAR PASS LIST |
Clears any unfilled PASS requests. |
|
.UTIL COMPILE PROC |
Compiles the specified Process Type/Name or Application. |
|
.UTIL DEL USER |
Deletes a user from the Appx User File. |
|
.UTIL DEL HOOK |
Deletes a record from the Hook File. |
|
.UTIL FIELD GET |
Retrieves the value of the specified field name. |
|
.UTIL FIELD SET |
Sets a value into the specified field name. |
|
.UTIL GET EM NAME |
For a given Process Type/Name, returns the Em name. |
|
.UTIL GET HOOK RECORDS |
Copies the engine Hook records into a temporary file for modification. |
|
.UTIL LOAD STACK FILE |
Loads --- STACK with the current process stack. |
|
.UTIL MOD SCROLL BEHAV |
This subroutine allows the user to select a record on a scrolling display by just clicking it. |
|
.UTIL PROCESS DD |
Processes the Data Dictionary for the selected Application or File. |
|
.UTIL PROCESS QRY REC |
Writes the current record to the Query pointer file. |
|
.UTIL PUT HOOK RECORDS |
Activates the hooks in the temporary file. |
|
.UTIL SLEEP |
Pauses for the specified number of seconds. |
|
.UTIL SLEEP WITH TIMER |
Pauses for the specified number of seconds with a countdown timer. |
|
.UTIL SWITCH USER |
Changes to a different user. |
|
.UTIL TIMEOUT EXIT |
Exits or logout a user after a set timeout period. |
|
.UTIL TIMEOUT SET |
Sets the keyboard timeout value. |
|
.UTIL UPDATE DOCUMENT |
Update process documentation via ILF. |
Web Processing Contains the routine to populate Appx variables from a CGI Script.
|
API Name |
Description |
|
.IMPORT CGI DATA |
Populates Appx Variables from STDIN. |
Widget Routines Contains routines to apply a theme to your GUI screens, convert colors (including the new transparency option), turn the standard menus and buttons on or off, debug the current --- WIDGET file, copy to/from the --- WIDGET file, and more.
|
API Name |
Description |
|
.WIDGET APPLY THEME |
Applies a GUI Theme to the current image. |
|
.WIDGET CNV CLR TO RGB |
Converts an alpha/hex color code to decimal. |
|
.WIDGET CNV RGB TO CLR |
Converts a decimal color code to alpha/hex. |
|
.WIDGET DEL BY NAME |
Deletes selected widgets. |
|
.WIDGET DEL MODE BTN |
Deletes the mode buttons from the toolbar. |
|
.WIDGET DEL SCROLL BTN |
Deletes the scroll buttons from the toolbar. |
|
.WIDGET DEL STD MENUS |
Deletes the standard pull down menus. |
|
.WIDGET HIDE BY NAME |
Hides selected widgets. |
|
.WIDGET HIDE MODE BTN |
Hides the mode buttons on the toolbar. |
|
.WIDGET HIDE SCROL BTN |
Hides the scroll buttons on the toolbar. |
|
.WIDGET HIDE STD MENUS |
Hides the standard pull down menus. |
|
.WIDGET MISSING THEME |
Finds all Inputs/Menus that do not use .WIDGET APPLY THEME. |
|
.WIDGET SET FROM MWDGT |
Copies the memory file to --- WIDGET. |
|
.WIDGET SET INTO MWDGT |
Copies the current --- WIDGET file to a memory file. |
|
.WIDGET SET THEME |
Sets the current Theme Name. |
|
.WIDGET SHOW BY NAME |
Shows previously hidden widgets. |
|
.WIDGET SHOW MODE BTN |
Shows previously hidden mode buttons on the toolbar. |
|
.WIDGET SHOW SCROL BTN |
Shows previously hidden scroll buttons on the toolbar. |
|
.WIDGET SHOW STD MENUS |
Shows the previously hidden standard pull down menus. |
|
WIDGET VIEW RUNTIME |
Shows properties of the current --- WIDGET file. |
Data Manipulation
Conversion Contains routines to convert data to/from Hex, splits a number into its whole and fractional parts, convert a text field to HTML encoding, and more.
|
API Name |
Description |
|
.CONVERT BYTES TO HEX |
Converts a field to hexadecimal characters. |
|
.CONVERT HEX PR TO NUM |
Converts a hex pair of alpha characters to a decimal number. |
|
.CONVERT NUM TO HEX PR |
Converts a decimal number to a hex pair of alpha characters. |
|
.CONVERT SPLIT NUMBER |
Splits a number into its whole and fractional parts. |
|
.CONVERT TEXT TO HTML |
Converts a text field to HTML encoding. |
|
.CONVERT TRANSLATE |
Converts a string from one language to another. |
Text Contains routines to fill a field with a character, search & replace text, convert to/from upper/lower case, parse a line into fields, and more.
|
API Name |
Description |
|
.TEXT CREATE PAD |
Fills a field with a single character. |
|
.TEXT CUT AT POS |
Removes characters from a text/alpha field. |
|
.TEXT FIND |
Find the position of text in a text/alpha field. |
|
.TEXT FIND AND REPLACE |
Find and replace text in a text/alpha field. |
|
.TEXT GET LENGTH |
Determine the length of a text/alpha field. |
|
.TEXT INSERT AT POS |
Inserts characters into a text/alpha field. |
|
.TEXT LOWER TO UPPER |
Convert lower case to upper case in a text/alpha field. |
|
.TEXT PARSE LINE |
Parse a string into separate fields. |
|
.TEXT UPPER TO LOWER |
Convert upper case to lower case in a text/alpha field. |
System Information
Environment Contains routines to get the command line parameters, environment variables, configuration information, parent process name, data file paths, application license info, and more.
|
API Name |
Description |
|
.ENV GET APPXPATH |
Returns the path to the location of Appx data files. |
|
.ENV GET CMD LINE PARM |
Returns the value of a command line parameter. |
|
.ENV GET CONFIG INFO |
Populates PDF fields with configuration information. |
|
.ENV GET ENV VARIABLE |
Returns the value of an environment variable. |
|
.ENV GET OS TYPE |
Return the type of operating system Appx is running on. |
|
.ENV GET PARENT PROC |
Returns the name and type of the parent process. |
|
.ENV GET PATH NAME |
Returns the pathname of the requested APPX data file. |
|
.ENV GET PATH SEP |
Returns the directory separator character of the host operating system. |
|
.ENV GET SCREEN SIZE |
Returns the size of the Appx screen in rows and columns. |
|
|
|
|
.ENV VIEW LICENSE INFO |
Displays the APPX license info for the current application. |
Client Contains routines to check the client version, upload/download files (with and without conversion), read/write the clipboard, and load a URL. In particular, the .CLIENT LOAD URL routine has been significantly enhanced to print or display files, start new sessions, and change client settings.
|
API Name |
Description |
|
.CLIENT CHECK FOR GUI |
Returns a flag to indicate if the user is running the Desktop Client. |
|
.CLIENT CHECK VERSION |
Returns the version of the Desktop Client. |
|
CLIENT DOWNLOAD FILE |
Downloads a file to the user's PC. |
|
.CLIENT GET CLIPBOARD |
Gets the current content of the system clipboard. |
|
.CLIENT GET CONSTANT |
Returns the value of a client constant. |
|
.CLIENT LOAD URL |
Loads a URL, document, runs a command on the user's PC or changes a client setting. |
|
.CLIENT PLAY SOUND |
Plays a .wav file on the user's PC. |
|
.CLIENT SET CLIPBOARD |
Puts data on the system clipboard. |
|
.CLIENT UPLOAD FILE |
Uploads a file from the Client to the server. |
File System
File Manipulation Contains routines to perform a variety of file operations, creating, copying, archiving, deleting, moving, restructuring and more.
|
API Name |
Description |
|
.FILE COPY |
Copies a file from one location to another, creating any required directories. |
|
.FILE CREATE |
Creates the specified file. |
|
.FILE CREATE ARCHIVE |
Creates an archive of the specified files, in either TAR or TGZ format. |
|
.FILE DELETE |
Deletes the given file from the filesystem. |
|
.FILE EXISTS |
Tests for the existence of the given file in the filesystem. |
|
.FILE EXTRACT ARCHIVE |
Extracts all the files from a previously created archive. |
|
.FILE MAKE DIR |
Creates the given directory and parent directories in the filesystem. |
|
.FILE MOVE |
Moves a file or directory from one location to another, creating any required directories |
|
.FILE RESTRUCT |
Restructures the specified file. |
|
.FILE SPLIT FILENAME |
Splits the filename from the file extension and returns both. |
|
.FILE SPLIT PATHNAME |
Splits the filename from the path and returns both. |
Stream Routines The stream processing routines have been significantly enhanced. You can now open multiple stream files at once, open STDIN:, STDOUT: and STDERR:, and open a URL to read a website directly.
|
API Name |
Description |
|
.STREAM CLOSE |
Closes a file stream and frees up the stream resources for that file. |
|
.STREAM CLOSE ALL |
Closes all file streams and frees up the stream resources for those files. |
|
.STREAM OPEN |
Opens a stream to the given file creating the file and path as needed. |
|
.STREAM READ |
Read data from the given stream. |
|
.STREAM WRITE |
Write data to the given stream. |
|